home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1994 March / Internet Info CD-ROM (Walnut Creek) (March 1994).iso / networking / terms / kermit / a / msxaaa.doc < prev    next >
Encoding:
Text File  |  1988-08-15  |  20.4 KB  |  552 lines
  1.  
  2.            SPECIFICATION FOR MS-DOS KERMIT SYSTEM-DEPENDENT MODULES
  3.  
  4.                       by Jeff Damens, Columbia University
  5.  
  6.    This document applies to Verson 2.28 of MS-DOS Kermit, and it has some
  7.    updates at the end for Version 2.29.  It has not been updated for 
  8.    version 2.30.
  9.  
  10. All the system-independent global data structures used in Kermit-MS are defined
  11. in the file MSDEFS.H.
  12.  
  13. The routine MSXxxx.ASM contains system-dependent support for system xxx, except
  14. for terminal emulation, which is in MSYxxx.ASM, described below.
  15.  
  16. The  routines  in the MSX module may change any registers but the stack pointer
  17. and segment registers, unless otherwise noted.  A routine that  returns  via  a
  18. RET  instruction is said to return normally; a routine that skip returns is one
  19. that returns to three bytes past the normal return address.
  20.  
  21. Global variables that must be defined in the system-dependent module:
  22.  
  23. XOFSNT          byte.  This should be set to a non-zero value if we  are  doing
  24.                 flow  control  and  have  sent  an XOFF character to the remote
  25.                 host, zero otherwise.
  26.  
  27. MACHNAM         byte.  A $-terminated string identifying the machine this  ver-
  28.                 sion of Kermit is for; it is printed when Kermit starts up.
  29.  
  30. SETKTAB         byte.  A keyword table associating terminal key names to 16-bit
  31.                 scan code values, used in the set key command.  If  the  kermit
  32.                 version  can accept arbitrary decimal values as scan codes, the
  33.                 word "SCAN" should appear in the table with a scan value of -1.
  34.                 If  key  redefinition is not implemented, the first byte of the
  35.                 table should be a zero.
  36.  
  37. SETKHLP         byte.  A $-terminated string to be printed when ? is  typed  in
  38.                 the  SET KEY command.  This is usually simply a list of the key
  39.                 names in  SETKTAB.    SETKHLP  must  be  defined  even  if  key
  40.                 redefinition  is not implemented, to satisfy the linker; if key
  41.                 redefinition is not implemented, SETKHLP  will  never  be  dis-
  42.                 played.
  43.  
  44. COUNT           word.   The number of characters in the serial input buffer, if
  45.                 known.  This is how Kermit knows to send an XON if  the  serial
  46.                 handler  has  sent an XOFF.  If the number of characters in the
  47.                 buffer isn't known, COUNT should be 0.
  48.  
  49. These are the required entry points for the system dependent  dependent  module
  50. MSXxxx.ASM.
  51.  
  52. SERINI
  53.  
  54. Parameters      None.
  55.  
  56. Returns         Normally, no return value.
  57.  
  58. Description     Perform  any initialization that must be done before the serial
  59.                 port can be used, including setting baud rate,  interrupt  vec-
  60.                 tors, etc.  Parity and baud rate should be set according to the
  61.                 values in  the  PORTINFO  structure.    The  external  variable
  62.                 PORTVAL  points to the PORTINFO structure for the current port.
  63.                 Calling SERINI more than once without an  intervening  call  to
  64.                 SERRST should have no effect.
  65.  
  66.  
  67. SERRST
  68.  
  69. Parameters      None.
  70.  
  71. Returns         Normally, no return value.
  72.  
  73. Description     Undoes  any  initialization done by SERINI, including resetting
  74.                 the serial port, restoring any  interrupt  vectors  changed  by
  75.                 SERINI,  etc.  Calling this more than once without an interven-
  76.                 ing call to SERINI should be harmless.
  77.  
  78.  
  79. CLRBUF
  80.  
  81. Parameters      None.
  82.  
  83. Returns         Normally, no return value.
  84.  
  85. Description     Remove and discard from the  serial  port's  input  buffer  any
  86.                 characters  sent by the remote host that have not yet been read
  87.                 by Kermit, and set COUNT to 0.  This  is  used  before  a  file
  88.                 transfer  to flush NAK's that accumulate in the buffer when the
  89.                 remote host is in server mode.
  90.  
  91.  
  92. OUTCHR
  93.  
  94. Parameters      A character in AH.
  95.  
  96. Returns         Skip returns if the character  has  been  transmitted;  returns
  97.                 normally  if  the character can not be transmitted because of a
  98.                 hardware error.
  99.  
  100. Description     Sends the character in AH out  the  currently  selected  serial
  101.                 port.    OUTCHR  can  assume  that SERINI will have been called
  102.                 previously. OUTCHR should call the external  routine  DOPAR  to
  103.                 set  the parity of the character if the communications hardware
  104.                 doesn't automatically set  parity.    Flow  control  should  be
  105.                 honored;  the external variable PORTVAL contains a pointer to a
  106.                 PORTINFO structure (as defined in MSDEFS.H) containing the cur-
  107.                 rent flow control definitions.
  108.  
  109.  
  110. COMS
  111.  
  112. Parameters      None.
  113.  
  114. Returns         Normally  if  a parse error is encountered, skip returns other-
  115.                 wise.
  116.  
  117. Description     Called by the SET PORT command.  On  a  machine  with  multiple
  118.                 serial  ports,  COMS  should  parse for the name or number of a
  119.                 serial port and make that the port used by succeeding calls  to
  120.                 SERINI, PRTCHR, OUTCHR, and SERRST.  It should set the external
  121.                 variable PORTVAL to point to one of the  external  port  struc-
  122.                 tures  PORT1 or PORT2, and set COMFLG in the FLAGS structure to
  123.                 1 for port one, 0 for port 2.   For  implementations  that  use
  124.                 only  one  serial port, COMS should print a message to that ef-
  125.                 fect and skip return.
  126.  
  127.  
  128. VTS
  129.  
  130. Parameters      None.
  131.  
  132. Returns         Normally if a parse error is encountered, skip  returns  other-
  133.                 wise.
  134.  
  135. Description     Parses  for an ON or OFF, sets HEATH-19 emulation while in ter-
  136.                 minal emulation appropriately.  The VTFLG field  of  the  FLAGS
  137.                 structure  should  be set non-zero if HEATH-29 emulation is on,
  138.                 zero otherwise.  If HEATH-19 emulation is not done, VTS  should
  139.                 print a message and skip return.
  140.  
  141.  
  142. DODEL
  143.  
  144. Parameters      None.
  145.  
  146. Returns         Normally, no return value.
  147.  
  148. Description     Erases the character immediately to the left of the cursor from
  149.                 the screen, then backs up the cursor.
  150.  
  151.  
  152. CTLU
  153.  
  154. Parameters      None.
  155.  
  156. Returns         Normally, no return value.
  157.  
  158. Description     Move the cursor to the left margin, then clear the line.
  159.  
  160.  
  161. CMBLNK
  162.  
  163. Parameters      None.
  164.  
  165. Returns         Normally, no return value.
  166.  
  167. Description     Clears the screen and homes the cursor.
  168.  
  169.  
  170. LOCATE
  171.  
  172. Parameters      None.
  173.  
  174. Returns         Normally, no return value.
  175.  
  176. Description     Homes the cursor.
  177.  
  178.  
  179. LCLINI
  180.  
  181. Parameters      None.
  182.  
  183. Returns         Normally, no return value.
  184.  
  185. Description     Performs any system-dependent initialization required  by  this
  186.                 implementation.
  187.  
  188.  
  189. PRTCHR
  190.  
  191. Parameters      None.
  192.  
  193. Returns         Normally,  with  the next character from the currently selected
  194.                 serial port in AL.  Skip returns if no character is available.
  195.  
  196. Description     Reads the next character from the current serial port.   PRTCHR
  197.                 can assume SERINI has been called previously, and should handle
  198.                 flow control correctly.
  199.  
  200.  
  201. DOBAUD
  202.  
  203. Parameters      None.
  204.  
  205. Returns         Normally, no return value.
  206.  
  207. Description     Sets the baud rate for the current port.  The baud rate  should
  208.                 be  obtained  from  the  BAUD  field of the PORTINFO structure,
  209.                 pointed to by the external variable PORTVAL.
  210.  
  211.  
  212. CLEARL
  213.  
  214. Parameters      None.
  215.  
  216. Returns         Normally, no return value.
  217.  
  218. Description     Clears from the cursor to the end of the current line.
  219.  
  220.  
  221. DODISK
  222.  
  223. Parameters      None.
  224.  
  225. Returns         Normally, no return value.
  226.  
  227. Description     Sets the external variable DRIVES to the number of disk  drives
  228.                 attached to the machine.
  229.  
  230.  
  231. GETBAUD
  232.  
  233. Parameters      None.
  234.  
  235. Returns         Normally, no return value.
  236.  
  237. Description     Store  current  baud rate of the currently selected port in the
  238.                 BAUD field of the current PORTINFO structure, which is  pointed
  239.                 to  by PORTVAL.  If the baud rate is to default to a particular
  240.                 value, this routine can store that value into  the  BAUD  field
  241.                 instead.
  242.  
  243.  
  244. BEEP
  245.  
  246. Parameters      None.
  247.  
  248. Returns         Normally, no return value.
  249.  
  250. Description     Rings the terminal bell.
  251.  
  252.  
  253. PUTHLP
  254.  
  255. Parameters      A pointer to a string in AX.
  256.  
  257. Returns         Normally, no return value.
  258.  
  259. Description     Writes  the null-terminated string given in AX to the terminal.
  260.                 This is used to display help and status messages.  The IBM  and
  261.                 Rainbow versions write the string in a reverse video box.
  262.  
  263.  
  264. PUTMOD
  265.  
  266. Parameters      A pointer to a string in AX.
  267.  
  268. Returns         Normally, no return value.
  269.  
  270. Description     Writes  the null-terminated string given in AX to the last line
  271.                 of the screen, in inverse video if possible.
  272.  
  273.  
  274. CLRMOD
  275.  
  276. Parameters      None.
  277.  
  278. Returns         Normally, no return value.
  279.  
  280. Description     Clears the line written by PUTMOD.
  281.  
  282.  
  283. POSCUR
  284.  
  285. Parameters      Row in DH, column in DL.
  286.  
  287. Returns         Normally, no return value.
  288.  
  289. Description     Positions the cursor to the row and column given in DX.    Rows
  290.                 and columns both originate at 0 (not 1!).
  291.  
  292.  
  293. SENDBR
  294.  
  295. Parameters      None.
  296.  
  297. Returns         Normally, no return value.
  298.  
  299. Description     Send a break to the current serial port.
  300.  
  301.  
  302. SHOWKEY
  303.  
  304. Parameters      Pointer to a terminal argument block in AX (see TERM below).
  305.  
  306. Returns         Normally,  with  a  string  pointer in AX and the length of the
  307.                 string in CX.
  308.  
  309. Description     Called by the SHOW KEY command.  Reads a key from the  terminal
  310.                 and returns a string containing implementation-dependent infor-
  311.                 mation about the key. In the usual case,  the  string  contains
  312.                 the  key's (machine-dependent) scan code, and the key's defini-
  313.                 tion (if any) from the terminal argument block.  The length  of
  314.                 the  returned  string should be returned in CX.  The string may
  315.                 contain any characters; unprintable characters will  be  quoted
  316.                 when  the  string  is  printed.  If the implementation does not
  317.                 support key redefinition, SHOWKEY may return  a  static  string
  318.                 saying so.
  319.  
  320.  
  321. TERM
  322.  
  323. Parameters      Pointer to terminal argument block in AX.
  324.  
  325. Returns         Normally, no return value.
  326.  
  327. Description     Do  terminal  emulation,  based  on  argument  block  described
  328.                 below...
  329.  
  330. The following entry points were added for version 2.29 by  Joe  R.  Doupnik  of
  331. Utah State University (May 1986):
  332.  
  333.  
  334. DTRLOW
  335.  
  336. Parameters      None.
  337.  
  338. Returns         Return-skip normally or just Return if command not confirmed.
  339.  
  340. Description     Parses HANGUP command and calls local procedure SERHNG to lower
  341.                 modem control lines DTR and RTS.  Most MS Kermits have not  im-
  342.                 plemented  SERHNG; a "not implemented" message results in these
  343.                 cases.
  344.  
  345.  
  346. DUMPSCR
  347.  
  348. Parameters      None.
  349.  
  350. Returns         Normally.
  351.  
  352. Description     Copies text from the screen to a file. Word DMPNAME  holds  the
  353.                 address (offset in data segment) of a zero terminated string of
  354.                 the filename or  device;  the  default  string  is  KERMIT.SCN;
  355.                 MSSSET  stores this string. Method of copying is to capture the
  356.                 screen to a buffer and read out the text to a file, with  lines
  357.                 trimmed of trailing blanks and terminated by CR/LF. A Form Feed
  358.                 ends the file. The filename is checked for collision with  sys-
  359.                 tem,  readonly,  subdirectory types etc and a complaint message
  360.                 is displayed if such a collision occurs.  The  file  is  opened
  361.                 and  closed  for each screen dump operation.  Current implemen-
  362.                 tations are on IBM and Rainbow machines, and  they  append  new
  363.                 material  to  a  pre-existing  file.  On other systems a simple
  364.                 Return is done.
  365.  
  366.  
  367. IHOSTR
  368.  
  369. Parameters      None.
  370.  
  371. Returns         Normally.
  372.  
  373. Description     Initializes the remote host for our  reception  of  a  file  by
  374.                 sending  the  flow-on  character  (XON normally) to release any
  375.                 held data. Called by receive-file code just after  initing  the
  376.                 serial port.
  377.  
  378.  
  379. IHOSTS
  380.  
  381. Parameters      None.
  382.  
  383. Returns         Normally.
  384.  
  385. Description     Initializes  the  host for our sending of a file by sending the
  386.                 flow-on character (XON normally) to release any held data, such
  387.                 as NAKs, flushes the serial port input buffer, waits one second
  388.                 (by calling SLEEP), and exits if the buffer is empty.    Other-
  389.                 wise, the cycle of clear buffer, sleep one second, check buffer
  390.                 is repeated. Called by send-file routine just after  initializ-
  391.                 ing the serial port.
  392.  
  393.  
  394. VTS
  395.  
  396. Parameters      None.
  397.  
  398. Returns         Skip-return normally or just Return if parser error.
  399.  
  400. Description     Parses  SET  TERM  commands.  The IBM version has many keywords
  401.                 which are further parsed and cause  jumps  to  action  routines
  402.                 within  this  procedure.  Non-IBM  Kermits  usually  parse  the
  403.                 keywords ON and OFF, for Heath-19 emulation or not.  Common  to
  404.                 all  MS  Kermits  is the setting of global byte FLAGS.VTFLG in-
  405.                 dicating the terminal emulation type (types are defined in  the
  406.                 header file MSSDEF.H). For the VT102 emulator in the IBM Kermit
  407.                 VTS also writes into structure VTEMU to pass information to the
  408.                 emulator  about colors, tabstops, line-wrap, and other Set Term
  409.                 parameters and controls global byte REFRESH  passed  to  module
  410.                 MSYIBM to govern screen refresh methodology.  Small local pars-
  411.                 ing support procedures are included here.
  412.  
  413.                 Structure VTEMU is defined in header file MSSDEF.H and contains
  414.                 the following fields:
  415.  
  416.  
  417.                 VTFLGST         Byte.  Holds  VT102 setup flag bits, which when
  418.                                 set mean -
  419.  
  420.                                 VSNEWLINE (01H)
  421.                                     ANSI Newline mode active
  422.  
  423.                                 VSWRAP (02H)
  424.                                     Line wrap is active
  425.  
  426.                                 VSSHIFT3 (04H)
  427.                                     Sharp sign (#) replaced by Pound Sterling
  428.  
  429.                                 VSKEYCLICK (08)
  430.                                     Keyclick on
  431.  
  432.                                 VSMARGINBELL (10H)
  433.                                     Sound bell when cursor passes column 72
  434.  
  435.                                 VSCURSOR (20H)
  436.                                     Cursor is a block (vs underline)
  437.  
  438.                                 VSSCREEN (40H)
  439.                                     Screen is to be reverse video
  440.  
  441.                                 A  constant VSDEFAULTS is defined in the header
  442.                                 file as the OR of bits above which is  used  by
  443.                                 the  emulator at Kermit startup time in lieu of
  444.                                 Set Term.
  445.  
  446.                 VTTBS           Word. Holds address (offset in data segment) to
  447.                                 default  tabstop  byte array. This array is lo-
  448.                                 cated in file MSZIBM.
  449.  
  450.                 VTTBST          Word. Holds address (offset in data segment) to
  451.                                 active  tabstop  byte  array. This array is lo-
  452.                                 cated in file MSZIBM.
  453.  
  454.                 ATT_PTR         Word. Pointer (offest in data segment) to video
  455.                                 attributes  byte  pair (which is stored in file
  456.                                 MSZIBM).
  457.  
  458. Further, global byte FLAGS.VTFLG holds the kind  of  terminal  being  emulated.
  459.                 Kinds are defined in the header file as constants:
  460.  
  461.                     TTGENERIC       0       no emulation
  462.                     TTHEATH         1       Heath-19
  463.                     TTVT52          2       VT52 submode of VT102
  464.                     TTVT102         3       VT102
  465.                     TTTYPES         4       number of types defined above.
  466.  
  467.  
  468. VTSTAT
  469.  
  470. Parameters      Enter with register DI pointing to status buffer STTBUF.
  471.  
  472. Returns         Register  CX counting the right most column used in status dis-
  473.                 play and register DI 40 bytes larger that at entry.  Uses  nor-
  474.                 mal Return, not Skip-return.
  475.  
  476. Description     Displays  Status information about terminal emulator. Called by
  477.                 procedure STAT0 in file MSSSET. This procedure  is  similar  to
  478.                 normal  Status  ones  except  the data items are from structure
  479.                 VTEMU. Command macros for VTSTAT are defined  in  file  MSXxxx.
  480.                 VTSTAT writes the status information directly to the screen and
  481.                 returns to STAT0 with character in line pointer register DI set
  482.                 40  bytes  larger  than when entered (even though several lines
  483.                 may have been displayed) and register CX holding the number  of
  484.                 chars  shown on the last line. Non-IBM Kermits just do a simple
  485.                 Return. Normally VTSTAT is  the  last  Status  item  called  by
  486.                 STAT0.
  487.  
  488. Terminal  emulation  is  supplied in the system dependent files MSXxxx, MSYxxx,
  489. and possibly MSZxxx, depending on the machine. The  terminal  "argument  block"
  490. passed  to procedure TERM is listed below; but note that the VT102 emulator for
  491. IBM machines uses an additional global structure VTEMU.  The terminal  argument
  492. block passed to the terminal emulator has the following fields:
  493.  
  494. FLGS            Byte containing flags.  Flags are:
  495.  
  496.                 SCRSAM (80H)    If   on,   the   terminal   emulator  shouldn't
  497.                                 re-display the screen when entered.
  498.  
  499.                 CAPT (40H)      Capture output.  If on, the routine  passed  in
  500.                                 field  CAPTR is called with each character sent
  501.                                 to the screen.
  502.  
  503.                 EMHEATH (20H)   On if terminal emulation is active.   Obsolete.
  504.                                 The   preferred   method  is  to  examine  byte
  505.                                 FLAGS.VTFLG for the terminal type.
  506.  
  507.                 HAVTT (10H)     A key redefinition table is present.
  508.  
  509.                 TRNCTL (08H)    Print control character X  as  ^X  (useful  for
  510.                                 debugging).
  511.  
  512.                 MODOFF (04H)    Do not display emulator mode line if on.
  513.  
  514.                 LCLECHO (01H)   Echo  keyboard  characters on the screen in ad-
  515.                                 dition to sending them to the port.
  516.  
  517. PRT             Port to use for terminal emulation, used  only  in  mode  line.
  518.                 This is just a copy of COMFLG in FLAGS.
  519.  
  520. COLS            Number of columns on screen.
  521.  
  522. ROWS            Number of rows on screen.
  523.  
  524. CAPTR           Routine  to  call  to with each character sent to the screen if
  525.                 CAPT flag is on.  Characters are passed in AL.
  526.  
  527. BELLD           Bell divisor (used only on IBM).
  528.  
  529. KLEN            Number of keys in key redefinition table, if HAVTT flag is on.
  530.  
  531. KTAB            Address of key redefinition table.  The key redefinition  table
  532.                 is a table of KLEN 16-bit scan codes.  Each (machine dependent)
  533.                 scan code represents a key that is redefined.
  534.  
  535. KRPL            Address of key replacement table.  The  key  replacement  table
  536.                 parallels the key redefinition table given in KTAB.  Entries in
  537.                 the replacement table are  16-bit  pointers  to  redefinitions.
  538.                 Each  redefinition  has  a  one-byte  length,  followed  by the
  539.                 definition.
  540.  
  541. ESCC            Escape character (single byte).  When this character  is  typed
  542.                 to the emulator, it should return.
  543.  
  544. BAUDB           byte.    Bits  describing the baud rate so it can be printed on
  545.                 the mode line.  This is a copy of the BAUD field  in  the  POR-
  546.                 TINFO structure.  Currently used only on the IBM.  See MSDEFS.H
  547.                 for possible values.
  548.  
  549. PARITY          byte.  Current parity to print on the mode line.    This  is  a
  550.                 copy  of PARFLG in the PORTINFO structure.  Currently used only
  551.                 on the IBM.  See MSDEFS.H for possible values.
  552.